package com.welson.restfultoolx.service;

import java.util.Optional;
import java.util.concurrent.TimeUnit;

/**
 * 缓存管理器接口
 * 提供高性能的内存缓存功能
 */
public interface CacheManager {
    
    /**
     * 存储缓存项
     * @param key 缓存键
     * @param value 缓存值
     */
    void put(String key, Object value);
    
    /**
     * 存储带过期时间的缓存项
     * @param key 缓存键
     * @param value 缓存值
     * @param ttl 生存时间
     * @param timeUnit 时间单位
     */
    void put(String key, Object value, long ttl, TimeUnit timeUnit);
    
    /**
     * 获取缓存项
     * @param key 缓存键
     * @param type 值类型
     * @param <T> 泛型类型
     * @return 缓存值的Optional包装
     */
    <T> Optional<T> get(String key, Class<T> type);
    
    /**
     * 获取缓存项（兼容旧版本）
     * @param key 缓存键
     * @param type 值类型
     * @param <T> 泛型类型
     * @return 缓存值，如果不存在则返回null
     */
    <T> T get(String key, Class<T> type, T defaultValue);
    
    /**
     * 检查缓存项是否存在
     * @param key 缓存键
     * @return 是否存在
     */
    boolean containsKey(String key);
    
    /**
     * 移除缓存项
     * @param key 缓存键
     * @return 是否成功移除
     */
    boolean remove(String key);
    
    /**
     * 使缓存项失效
     * @param key 缓存键
     */
    void invalidate(String key);
    
    /**
     * 清空所有缓存
     */
    void clear();
    
    /**
     * 获取缓存大小
     * @return 缓存项数量
     */
    long size();
    
    /**
     * 获取缓存统计信息
     * @return 缓存统计
     */
    CacheStats getStats();
    
    /**
     * 清理过期的缓存项
     */
    void cleanUp();
    
    /**
     * 设置缓存的最大大小
     * @param maxSize 最大大小
     */
    void setMaxSize(long maxSize);
    
    /**
     * 缓存统计信息
     */
    interface CacheStats {
        long getHitCount();
        long getMissCount();
        double getHitRate();
        long getEvictionCount();
        long getLoadCount();
        double getAverageLoadTime();
    }
}